


WX AS 


koa 中 文 文档 


目录 


koa 中 文 文档 
简介 

安装 

应 用 
Context( 上 下 文 ) 
请 求 (Request) 
响应 (Response) 


相关 资源 


N O oO A OO N 


koa 中 文 文档 


来 源 : koa 中 文 文档 


koa 是 由 Express 原 班 人 马 打造 的 ， 致 力 于 成 为 一 个 更 小 、 更 富有 表现 力 、 更 健壮 的 Web 4E 
架 。 使 用 koa 编写 web 应 用 ， 通 过 组 合 不 同 的 generator， 可 以 免除 重复 繁琐 的 回调 函数 内 
套 ， 并 极 大 地 提升 错误 处 理 的 效率 。koa 不 在 内 核 方法 中 绑 定 任何 中 间 件 ， 它 仅仅 提供 了 一 个 
轻 量 优雅 的 函数 库 ， 使 得 编写 Web 应 用 变 得 得 心 应 手 。 


安装 


Koa 目前 需要 >=0.11.x 版 本 的 node 环境 。 并 需要 在 执行 node 的 时 候 附 带 --harmony 来 引入 
generators ° 如 果 您 安装 了 较 旧 版 本 的 node ， 您 可 以 安装 n (node 版 本 控制 器 )， 来 快速 安 
装 0.11.x 

$ npm install -g n 


$ n 0.11.12 
$ node --harmony my-koa-app.js 


Koa 应 用 是 一 个 包含 一 系列 中 间 件 generator 函数 的 对 象 。 这 些 中 间 件 函数 基于 request 请 

求 以 一 个 类 似 于 栈 的 结构 组 成 并 依次 执行 。 Koa 类 似 于 其 他 中 间 件 系统 (比如 Ruby's Rack 
` Connect 等 ) ， 然 而 Koa 的 核心 设计 思路 是 为 中 间 件 层 提供 高 级 语法 糖 封装 ， 以 增强 其 互 
用 性 和 健壮 性 ， 并 使 得 编写 中 间 件 变 得 相当 有 趣 。 


Koa 包含 了 像 content-negotiation (内 容 协商 ) 、cache freshness (缓存 刷新 ) 、proxy 
support (代理 支持 ) 和 redirection ( 重 定向 ) 等 常用 任务 方法 。 与 提供 庞大 的 函数 支持 不 
同 ，Koa 只 包含 很 小 的 一 部 分 ， 因 为 Koa 并 不 绑 定 任何 中 间 件 。 


任何 教程 都 是 从 hello world 开始 的 ，Koa 也 不 例外 ^ 人 ^ 


var koa 
var app 


require('koa'); 
koa(); 


app.use(function *) (1 
this.body = 'Hello World'; 
}); 


app.listen(3000); 


中 间 件 级 联 


Koa 的 中 间 件 通过 一 种 更 加 传统 (您 也 许 会 很 熟悉 ) 的 方式 进行 级 联 ， 握 弃 了 以 往 node 频繁 
的 回调 函数 造成 的 复杂 代码 逻辑 。 我 们 通过 generators K RAAE” i P 4 ° Connect 简 
单 地 将 控制 权 交 给 一 系列 函数 来 处 理 ， 直 到 有 通 数 返回 。 与 之 不 同 ， 当 执行 到 yield next 语 
ejut > Koa 暂停 了 该 中 间 件 ， 继 续 执行 下 一 个 符合 请 求 的 中 间 件 (downstrem'")， 然 后 控制 权 
ARRAY EB F lal (‘upstream’) 。 


下 面 的 例子 在 页 面 中 返回 "Hello World"， 然 而 当 请 求 开 始 时 ， 请 求 先 经 过 x-response-time 

和 logging 中 间 件 ， 并 记录 中 间 件 执行 起 始 时 间 。 然后 将 控制 权 交 给 reponse 中 间 件 。 当 
中 间 件 运行 到 yield next 时 ， By AE AL FG AE Hl 前 交 给 下 一 个 中 间 件 。 当 没有 中 间 件 执行 
yield next 时 ， 程 序 栈 会 逆序 唤起 被 挂 起 的 中 间 件 来 执行 接 下 来 的 代码 。 


var koa 
var app 


= require('koa'); 
= koa(); 


// x-response-time 


app.use(function *(next){ 
var start = new Date; 
yield next; 
var ms = new Date - start; 
this.set('X-Response-Time', ms + 'ms'); 


H; 
// logger 


app.use(function *(next){ 
var start = new Date; 
yield next; 
var ms = new Date - start; 
console.log('%s %s - %s', this.method, this.url, ms); 


H); 

// response 

app.use(function *(){ 
this.body = 'Hello World'; 

H); 


app.listen(3000); 


配置 


应 用 配置 是 app 实例 属性 ， 目 前 支持 的 配置 项 如 下 : 


© app.name 应 用 名 称 (可 选项 ) 

e app.env 默认 为 NODE_ENV 或 者 development 

e app.proxy 如 果 为 true ， 则 解析 "Host" 的 header 域 ， 并 支持 x-Forwarded-Host 
© app.subdomainoffset 歌 认 为 2， 表 示 .subdomains 所 忽略 的 字符 偏 移 量 


app.listen(...) 
Koa 应 用 并 非 是 一 个 1-to-1 表征 关系 的 HTTP 服务 器 。 一 个 或 多 个 Koa 应 用 可 以 被 挂 载 到 一 
起 组 成 一 个 包含 单一 HTTP 服务 器 的 大 型 应 用 群 。 


如 下 为 一 个 绑 定 3000 端 口 的 简单 Koa 应 用 ， 其 创建 并 返回 了 一 个 HTTP 服务 器 ， 为 
Server#listen() 传递 指定 参数 (参数 的 详细 文档 请 查看 nodejs.org) ° 


var koa = require('koa'); 
var app = koa(); 
app.listen(3000); 


app.listen(...) 实际 上 是 以 下 代码 的 语法 糖 : 


var http = require('http'); 

var koa = require('koa'); 

var app = koa(); 
http.createServer(app.callback()).listen(3000) ; 


这 意味 着 您 可 以 同时 支持 HTTPS 和 HTTPS， 或 者 在 多 个 端口 监听 同一 个 应 用 。 


var http = require('http'); 

var koa = require('koa'); 

var app = koa(); 
http.createServer(app.callback()).listen(3000) ; 
http.createServer(app.callback()).listen(3001) ; 


app.callback() 

返回 一 个 适合 http.createserver() 方法 的 回调 函数 用 来 处 理 请 求 。 您 也 可 以 使 用 这 个 回调 
函数 将 您 的 app 挂 载 在 Connect/Express 应 用 上 。 

app.use(function) 


为 应 用 添加 指定 的 中 间 件 ， 详 情 请 看 Middleware 


app.keys= 
设置 签名 Cookie 密 钥 ， 该 密 钥 会 被 传递 给 KeyGrip ° 
当然 ， 您 也 可 以 自己 生成 KeyGrip 实例 : 


app.keys 
app.keys 


['im a newer secret', '1 like turtle']; 
new KeyGrip(['im a newer secret', 'i like turtle'], 'sha256'); 


在 进行 cookie 签 名 时 ， 只 有 设置 signed A true 的 时 候 ， 才 会 使 用 密 钥 进行 加 密 : 


this.cookies.set('name', 'tobi', { signed: true }); 


错误 处 理 


默认 情况 下 Koa 会 将 所 有 错误 信息 输出 到 stderr， 除 非 NODE_ENV 是 "test"。 为 了 实现 自 定 
义 错误 处 理 逻 辑 (比如 centralized logging) ， 您 可 以 添加 "error" 事件 监听 器 。 
app.on('error', function(err){ 


log.error('server error', err); 


H); 


如 果 错 误 发 生 在 请 求 / 响 应 环节 ， 并 且 其 不 能 够 响应 客户 端 时 ， contenxt 实例 也 会 被 传递 到 
error 事件 监听 器 的 回调 函数 里 。 


app.on('error', function(err, ctx){ 
log.error('server error', err, ctx); 


3); 


当 发 生 错误 但 仍 能 够 响应 客户 端 时 〈 比 如 没有 数据 写 到 socket 中 ( ，Koa 会 返回 一 个 500 错 误 
(Internal Server Error) ° 


无 论 哪 种 情况 ，Koa 都 会 生成 一 个 应 用 级 别 的 错误 信息 ， 以 便 实现 日 志 记 录 等 目的 。 


Context( F x) 


Koa Context 将 node 的 request 和 response 对 象 封 装 在 一 个 单独 的 对 象 里 面 ， 其 为 编写 
web 应 用 和 API 提供 了 很 多 有 用 的 方法 。 


这 些 操作 在 HTTP 服务 器 开发 中 经 常 使 用 ， 因 此 其 被 添加 在 上 下 文 这 一 层 ， 而 不 是 更 高 层 框 
架 中 ， 因 此 将 迫使 中 间 件 需要 重新 实现 这 些 常 用 方法 。 


context 在 每 个 request 请 求 中 被 创建 ， 在 中 间 件 中 作为 接收 器 (receiven) 来 引用 ， 或 者 通过 
this 标识 符 来 引用 : 


app.use(function *(){ 
this; // is the Context 
this.request; // is a koa Request 
this.response; // is a koa Response 


3); 


许多 context 的 访问 器 和 方法 为 了 便于 访问 和 调用 ， 简 单 的 委托 给 他 们 的 ctx.request 和 
ctx.response 所 对 应 的 等 价 方法 ， 比如 说 ctx.type 和 ctx.length 代理 了 response 对 象 
中 对 应 的 方法 ， ctx.path 和 ctx.method 代理 了 request 对 象 中 对 应 的 方法 。 


API 


Context 详细 的 方法 和 访问 器 。 


ctx.req 


Node 的 request xt o 


ctx.res 
Node 的 response 对 象 。 
Koa 不 支持 直接 调用 底层 res 进行 响应 处 理 。 请 避免 使 用 以 下 node 属性 : 


© res.statusCode 
© res.writeHead() 
© res.write() 


© res.end() 


ctx.request 


Koa 的 Request xt Bo 


ctx.response 


Koa 的 Response xt o 


ctx.app 


应 用 实例 引用 。 


ctx.cookies.get(name, [options]) 
获得 cookie 中 名 为 name 的 值 ， options 为 可 选 参数 : 
٠ ‘signed’: 如 果 为 true， 表 示 请 求 时 cookie 需要 进行 签名 。 


注意 : Koa 使 用 了 Express 的 cookies 模块 ，options 参数 只 是 简单 地 直接 进行 传递 。 


ctx.cookies.set(name, value, [options]) 
设置 cookie 中 名 为 name 44° options 为 可 选 参 数 : 


© signed : 是 否 要 做 签名 

e expires : cookie 有 效 期 时 间 

e path : cookie 的 路 径 ， RUA /' 

e domain : cookie 的 域 

e secure : false 表示 cookie 通过 HTTP 协议 发 送 ，true 表示 cookie 通过 HTTPS 发 送 。 
e httponly : true 表示 cookie 只 能 通过 HTTP 协议 发 送 


注意 : Koa 使 用 了 Express 的 cookies 模块 ，options 参数 只 是 简单 地 直接 进行 传递 。 


ctx.throw(msg, [status]) 


Yow LS status 属性 的 错误 ， 黑 认为 500 。 该 方法 可 以 让 Koa 准确 的 响应 处 理 状态 。 
Koa 支 持 以 下 组 合 : 

this,throw(403) 

this.throw('name required', 400) 


this.throw(400, 'name required ) 
this.throw('something exploded' ) 


this.throw('name required', 400) 等 价 于 : 


var err = new Error('name required'); 
err.status = 400; 
throw err; 


注意 : 这 些 用 户 级 错误 被 标记 为 


ctx.respond 


err.expose ， 其 意味 着 这 些 消 息 被 准确 描述 为 对 客户 端的 响 
应 ， 而 并 非 使 用 在 您 不 想 泄露 失败 细节 的 场景 中 。 


为 了 避免 使 用 Koa 的 内 置 响应 处 理 功 能 ， 您 可 以 直接 赋值 this.repond = false; 。 如 果 您 不 
想 让 Koa 来 帮助 您 处 理 reponse， 而 是 直接 操作 原生 res 对 象 ， 那 么 请 使 用 这 种 方法 。 


注意 : 这 种 方式 是 不 被 Koa 支持 的 。 其 可 能 会 破坏 Koa 中 间 件 和 Koa 本 身 的 一 些 功能 。 其 
只 作为 一 种 hack 的 方式 ， 并 只 对 那些 想 


法 的 人 来 说 会 带 来 便利 。 


Request aliases 


以 下 访问 器 和 别名 与 Request FH : 


© ctx. 
@ ctx. 
© ctx. 
© ctx. 
© ctx. 
@ ctx 
© ctx. 
© ctx. 
© ctx. 
© ctx 
© ctx. 
© ctx. 
© ctx. 
© ctx. 
© ctx. 
© ctx. 
© ctx. 
@ ctx. 
© ctx. 
© ctx. 
@ ctx. 


header 
method 
method= 
url 


url= 


.originalUrl 


path 
path= 


query 


.query= 


querystring 
querystring= 
host 
hostname 
fresh 

stale 

socket 
protocol 
secure 

ip 


ips 


要 在 Koa 方法 和 中 间 件 中 使 用 传统 fn(req, res) 2 


© ctx.subdomains 

© ctx.is() 

© ctx.accepts() 

© ctx.acceptsEncodings() 
© ctx.acceptsCharsets() 
© ctx.acceptsLanguages() 


© ctx.get() 


Response aliases 


以 下 访问 器 和 别名 与 Response 等 价 : 


© ctx.body 

© ctx.body= 

© ctx.status 

© ctx.status= 

© ctx.length= 

© ctx.length 

© ctx.type= 

© ctx.type 

© ctx.headerSent 

© ctx.redirect() 

© ctx.attachment() 
© ctx.set() 

© ctx.remove() 

© ctx.lastModified= 


© ctx.etag= 


+4 (Request) 


Koa Request 对 象 是 对 node 的 request 进一步 抽象 和 封装 ， 提 供 了 日 常 HTTP 服务 器 开发 
中 一 些 有 用 的 功能 。 


API 


req.header 
TRA R 
req.method 
请 求 方法 
req.method= 


设置 请 求 方法 ， 在 实现 中 间 件 时 非常 有 用 ， 比 如 methodoverride() ° 


req.length 


以 数字 的 形式 返回 request 的 内 容 长 度 (Content-Length)， 或 者 返回 undefined ° 


req.url 
获得 请 求 url 地 址 。 
req.url= 


设置 请 求 地 址 ， 用 于 重 写 url 地 址 时 。 


req.originalUrl 


获取 请 求 原 始 地 址 。 


req.path 


获取 请 求 路 径 名 。 


req.path= 

设置 请 求 路 径 名 ， 并 保留 请 求 参数 (就 是 url 中 ?后 面 的 部 分 )。 
req.querystring 

获取 查询 参数 字符 串 (url 中 ?后 面 的 部 分 )， 不 包含 3。 


req.querystring= 


设置 查询 参数 。 


req.search 


获取 查询 参数 字符 串 ， 包 含 ?9。 


req.search= 


设置 查询 参数 字符 串 。 


req.host 


获取 host (hostname:port) ° 当 app.proxy 设置 为 true 时 ， 支 持 xX-Forwarded-Host ° 


req.hostname 


获取 hostname ° 4 app.proxy 设置 为 true 时 ， 支 持 x-Forwarded-Host ° 


req.type 
获取 请 求 content-type ， 不 包含 像 "charset" 这 样 的 参数 。 


var ct = this.request.type; 
// => “image/png" 


req.charset 
获取 请 求 charset， 没 有 则 返回 undefined : 


this.request.charset 
// => "utf-8" 


req.query 

将 查询 参数 字符 串 进 行 解析 并 以 对 象 的 形式 返回 ， 如 果 没有 查询 参数 字 字符 串 则 返回 一 个 空 
at Ho 

注意 : 该 方法 不 支持 误 套 和 解析。 


比如 "color=blue&size=small": 


{ 
color: 'blue', 
size: 'small' 


} 


req.query= 
根据 给 定 的 对 象 设置 查询 参数 字符 串 。 


注意 : BAER LAREN F © 


this.query = { next: '/login' }; 


req.fresh 


检查 请 求 缓存 是 否 "fresh"( 内 容 没 有 发 生变 化 )。 该 方法 用 于 在 If-None-Match / ETag , 


If-Modified-Since 和 Last-Modified 中 进行 缓存 协调 。 当 在 response headers 中 设置 一 个 
或 多 个 上 述 参 数 后 ， 该 方法 应 该 被 使 用 。 


this.set('ETag', '123'); 


// cache is ok 

if (this.fresh) { 
this.status = 304; 
return; 


} 


// cache is stale 
// fetch new data 
this.body = yield db.find('something'); 


req.stale 


与 req.fresh 相反 。 


req.protocol 


返回 请 求 协 议 ，"https" 或 者 "http"。 4 app.proxy 设置 为 true 时 ， 支 持 


X-Forwarded-Host ° 


req.secure 
简化 版 this.protocol == "https" ， 用 来 检查 请 求 是 否 通过 TLS 发 送 。 
req.ip 


请 求 远程 地 址 。 当 app.proxy 设置 为 true It > X44 x-Forwarded-Host ° 


req.ips 


x-Forwarded-For 存在 并 且 app.proxy 有 效 ， 将 会 返回 一 个 有 序 (从 upstream 到‏ كلا 
downstream) ip 数组 。 否则 返回 一 个 空 数组 。‏ 


req.subdomains 
以 数组 形式 返回 子 域名 。 


子 域名 RATS 过 号 分 隔 的 主 域名 前 面 的 部 分 。 默 认 情 况 下 ， 应 用 的 域名 假设 为 host 中 最 后 
两 部 分 。 其 可 通过 设置 app.subdomainoffset 进行 更 改 。 


举例 来 说 ， 如 果 域 名 是 "tobi.ferrets.example.com": 


如 果 没 有 设置 app.subdomainoffset ， 其 subdomains A ["ferrets", "tobi"] ° 如 果 设 置 
app.subdomainoffset 为 3， 其 subdomains 为 ["tobi"] ° 


req.is(type) 


检查 请 求 所 包含 的 "Content-Type" 是 否 为 给 定 的 type 值 。 如 果 没 有 request body > &E 
undefined ° 如 果 没 有 content type， 或 者 匹配 失败 ， 返 回 false 。 和 否则 返回 匹配 的 
content-type ° 


// With Content-Type: text/html; charset=utf-8 
this.is('html'); // => 'html' 
this.is('text/html'); // => 'text/html' 
this.is('text/*', 'text/html'); // => 'text/html' 


// When Content-Type is application/json 

this.is('json', 'urlencoded'); // => 'json' 
this.is('application/json'); // => 'application/json' 
this.is('html', 'application/*'); // => 'application/json' 


this.is('html'); // => false 


比如 说 您 希望 保证 只 有 图 片 发 送 给 指定 路 由 : 


if (this.is('image/*')) 1 

// process 
} else 1 

this.throw(415, ‘images only!'); 
} 


Content Negotiation 


Koa request 对 象 包 含 content negotiation 2 4% (由 accepts 和 negotiator 提供 ) 


© req.accepts(types) 
© req.acceptsEncodings(types) 
© req.acceptsCharsets(charsets) 


© req.acceptsLanguages(langs) 
如 果 没 有 提供 types， 将 会 返回 所 有 的 可 接受 类 型 。 


如 果 提 供 多 种 types， 将 会 返回 最 佳 匹 配 类 型 。 如 果 没 有 匹配 上 ， 则 返回 false ， 您 应 该 给 


客户 端 返回 406 "Not Acceptable" ° 


为 了 防止 缺少 accept headers 而 导致 可 以 接受 任意 类 型 ， 将 会 返回 第 一 种 类 型 。 因 此 ， 您 提 
供 的 类 型 顺序 非常 重要 。 


req.accepts(types) 


检查 给 定 的 类 型 types(s) 是 否 可 被 接受 ， 当 为 true 时 返回 最 佳 匹 配 ， 和 否则 返回 
false ° type 的 值 可 以 是 一 个 或 者 多 个 mime 类 型 字符 串 。 比如 "application/json" 扩展 名 
为 "json"， 或 者 数组 ["json", "html", "text/plain"] ° 


// Accept: text/html 
this.accepts('html'); 
// => "html" 


// Accept: text/*, application/json 
this.accepts('html'); 

// => "html" 
this.accepts('text/html'); 

// => "text/html" 
this.accepts('json', 'text'); 

// => "json" 
this.accepts('application/json'); 
// => “application/json" 


// Accept: text/*, application/json 
this.accepts('image/png'); 
this.accepts('png'); 

// => false 


// Accept: text/*;q=.5, application/json 
this.accepts(['html', 'json']); 
this.accepts('html', 'json'); 

// => "json" 


// No Accept header 
this.accepts('html', 'json'); 
// => "html" 
this.accepts('json', 'html'); 
// => "json" 


this.accepts() 可 以 被 调用 多 次 ， 或 者 使 用 switch: 


switch (this.accepts('json', 'html', 'text')) { 
case 'json': break; 
case 'html': break; 
case 'text': break; 
default: this.throw(406, 'json, html, or text only'); 


} 


req.acceptsEncodings(encodings) 


检查 encodings 是 否 可 以 被 接受 ， 当 为 true 时 返回 最 佳 匹 配 ， 否 则 返回 false 。 注意 
您 应 该 在 encodings 中 包含 identity ° 
// Accept-Encoding: gzip 
this.acceptsEncodings('gzip', 'deflate', '‘identity'); 
// => "gzip" 


this.acceptsEncodings(['gzip', 'deflate', ‘identity']); 
// => "gzip" 


当 没 有 传递 参数 时 ， 返 回 包 含 所 有 可 接受 的 encodings 的 数组 : 


// Accept-Encoding: gzip, deflate 
this.acceptsEncodings(); 
// => ["gzip", "deflate", "identity"] 


注意 : 如 果 客 户 端 直接 发 送 identity;q=9 时 ， identity encoding (表示 no encoding) 可 
以 不 被 接受 。 虽 然 这 是 一 个 边界 情况 ， 您 仍然 应 该 处 理 这 种 情况 。 


req.acceptsCharsets(charsets) 
检查 charsets 是 否 可 以 被 接受 ， 如 果 为 true MABRE’ SWRA false ° 


// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5 
this.acceptsCharsets('utf-8', ‘'utf-7'); 
// => “utf-8" 


this.acceptsCharsets(['utf-7', 'utf-8']); 
// => "utf-8" 


当 没 有 传递 参数 时 ， 返 回 包含 所 有 可 接受 的 charsets 的 数组 : 


// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5 
this.acceptsCharsets(); 
// => ["utf-8", "utf-7", "iso-8859-1"] 


req.acceptsLanguages(langs) 
检查 langs 是 否 可 以 被 接受 ， 如 果 为 true MARREL’ GUAE false ° 


// Accept-Language: en;q=0.8, es, pt 
this.acceptsLanguages('es', 'en'); 
// => Nast! 


this.acceptsLanguages(['en', 'es']); 
// => Nast! 


当 没 有 传递 参数 时 ， 返 回 包 含 所 有 可 接受 的 langs 的 数组 : 


// Accept-Language: en;q=0.8, es, pt 
this.acceptsLanguages(); 
// => ["es", "ot", "en" 


req.idempotent 
AEREE A 7 (idempotent) 。 


req.socket 


返回 请 求 的 Socket 。 


req.get(field) 


返回 请 求 header 中 对 应 field 49 fa ° 


"| 2 (Response) 
Koa Response 对 象 是 对 node 的 response 进一步 抽象 和 封装 ， 提 供 了 日 常 HTTP 服务 器 开 


发 中 一 些 有 用 的 功能 。 


API 


res.header 


Response header 对 象 。 


res.socket 


Request socket ° 


res.status 


获取 response status ° FFF node 在 默认 情况 下 res.statuscode 为 200， res.status 并 
没有 赋值 。 


res.statusString 


Response status 字符 串 。 


res.status= 
通过 数字 状态 码 或 者 不 区 分 大 小 写 的 字符 串 来 设置 response status : 


e 100 "continue" 

e 101 "switching protocols" 
e 102 "processing" 

e 200 "ok" 

201 "created" 

e 202 "accepted" 


e 203 "non-authoritative information" 
e 204 "no content" 

e 205 "reset content" 

e 206 "partial content" 

e 207 "multi-status" 


300 "multiple choices" 

301 "moved permanently" 

302 "moved temporarily" 

303 "see other" 

304 "not modified" 

305 "use proxy" 

307 "temporary redirect" 

400 "bad request" 

401 "unauthorized" 

402 "payment required" 

403 "forbidden" 

404 "not found" 

405 "method not allowed" 

406 "not acceptable" 

407 "proxy authentication required" 
408 "request time-out" 

409 "conflict" 

410 "gone" 

411 "length required" 

412 "precondition failed" 

413 "request entity too large" 
414 "request-uri too large" 

415 "unsupported media type" 
416 "requested range not satisfiable" 
417 "expectation failed" 

418 "i'm a teapot" 

422 "unprocessable entity" 

423 "locked" 

424 "failed dependency" 

425 "unordered collection" 

426 "upgrade required" 

428 "precondition required" 

429 "too many requests" 

431 "request header fields too large" 
500 "internal server error" 

501 "not implemented" 

502 "bad gateway" 

503 "service unavailable" 

504 "gateway time-out" 

505 "http version not supported" 


506 "variant also negotiates" 


507 "insufficient storage" 

509 "bandwidth limit exceeded" 

510 "not extended" 

511 "network authentication required" 


注意 : 不 用 担心 记 不 住 这 些 字符 串 ， 如 果 您 设置 错误 ， 会 有 异常 拢 出 ， 并 列 出 该 状态 码 表 来 
帮助 您 进行 更 正 。 
res.length= 


通过 给 定 值 设 置 response Content-Length 。 


res.length 

如 果 Content-Length 作为 数值 存在 ， 或 者 可 以 通过 res.body 来 进行 计算 ， 则 返回 相应 数 
值 ， 否则 返回 undefined ° 

res.body 


获得 response body ° 


res.body= 
设置 response body 为 如 下 值 : 


e string written 

e Buffer written 

» stream piped 

» object json-stringified 

e null no content response 


如 果 res.status 没有 赋值 ，Koa 会 自动 设置 为 200 或 204 ° 


String 


Content-Type RUA text/html 或 者 text/plain， 两 种 默认 charset 均 为 utf-8。 Content- 
Length 同时 会 被 设置 。 


Buffer 


Content-Type 默认 为 application/octet-stream，Content-Length 同 时 被 设置 。 


Stream 


Content-Type 默认 为 application/octet-stream ° 
Object 

Content-Type 默认 为 applicatiomjson ° 
res.get(field) 

获取 response header 中 字段 值 ，field 不 区 分 大 小 写 。 


var etag = this.get('ETag'); 


res.set(field, value) 
设置 response header 字段 field 的 值 为 value ° 


this.set('Cache-Control', 'no-cache'); 


res.set(fields) 
使 用 对 象 同 时 设置 response header 中 多 个 字段 的 值 。 


this.set({ 
"Etag': '1234', 
"Last-Modified': date 
3); 


res.remove(field) 


移 除 response header 中 字段 filed ° 


res.type 
获取 response content-type ， 不 包含 像 "charset" 这 样 的 参数 。 


var ct = this.type; 
// => "image/png" 


res.type= 


通过 mime 类 型 的 字符 串 或 者 文件 扩展 名 设置 response content-tType 


this.type "text/plain; charset=utf-8'; 


this.type = 'image/png'; 
this.type = '.png'; 
this.type = 'png'; 


注意 : 当 可 以 根据 res.type 确定 一 个 合适 的 charset 时， charset 会 自动 被 赋值 。 比如 
res.type = 'html' BẸ > charset 将 会 默认 设置 为 "utf-8"。 然 而 当 完 整定 义 为 

res.type = 'text/html' 时 ，charset 不 会 自动 设置 。 

res.redirect(url, [alt]) 

执行 [302] 重 定 向 到 对 应 url 。 


字符 串 "back" 是 一 个 特殊 参数 ， 其 提供 了 Referrer 支持 。 当 没有 Referrer 时 ， 使 用 alt 或 
者 / 代替 。 


this.redirect('back'); 
this.redirect('back', '/index.html'); 
this.redirect('/login'); 
this.redirect('http://google.com'); 


如 果 想 要 修改 默认 的 [302] 状态 ， 直 接 在 重 定向 之 前 或 者 之 后 执行 即 可 。 如 果 要 修改 body > 
需要 在 重 定向 之 前 执行 。 


this.status = 301; 
this.redirect('/cart'); 
this.body = 'Redirecting to shopping cart'; 


res.attachment([filename]) 


设置 "attachment" 的 content-Disposition ， 用 于 给 客户 端 发 送信 号 来 提示 下 载 。filename 
为 可 选 参数 ， 用 于 指定 下 载 文件 名 。 


res.headerSent 


检查 response header 是 否 已 经 发 送 ， 用 于 在 发 生 错 误 时 检查 客户 端 是 否 被 通知 。 


res.lastModified 


to RATE Last-Modified ， 则 以 pate 的 形式 返回 。 


res.lastModified= 


VA UTC 格式 设置 Last-Modified 。 您 可 以 使 用 pate X date 字符 串 来 进行 设置 。 


this.response.lastModified = new Date(); 


res.etag= 


设置 包含 " s 的 ETag。 注意 没有 对 应 的 res.etag 来 获取 其 值 。 


this.response.etag = crypto.createHash('md5').update(this.body).digest('hex'); 
res.append(field, val) 
在 header 的 field 后 面 追 加 val ° 


res.vary(field) 


相当 于 执行 res.append(Vary', field) ° 


相关 资源 


Community links to discover third-party middleware for Koa, full runnable examples， 
thorough guides and more! If you have questions join us in IRC! 以 下 列 出 了 更 多 第 三 方 提 供 
的 koa 中 间 件 、 完 整 实例 、 全 面 的 帮助 文档 等 。 如 果 有 问题 ， 请 加 入 我 们 的 IRC ! 


e GitHub repository 
e Examples 

e Middleware 

» Wiki 

e G+ Community 

e Mailing list 

e Guide 

e FAQ 

٠ #koajs on freenode 


